Literate Programming Revived

Literate programming[1] is a programming paradigm in which the finall form of clean code looks more like long-form prose. It takes the idea of writing code to another human AND for interpreter to it's logical conclusion; Writing primarily for human, and secondarily for interpreter.

Recently the web development community has found again literate programming, but in a new, even better form visual way. MDX[2] file format allows mixing code, documentation and prose into one file. Typescript[3], and jsdoc[4] let's us do formal documentation of API's that our tooling and interpreters can read. New component-based tooling like Storybook[5] let's us create interactive pieces of documentation and examples, instead of static prose. Together these tools create an interactive inventory of examples and 'tests' of the code, as well as human-readable documentation.

I think there are still a few missing pieces. I haven't found a good way to integrate component tests or Test-driven development[6] in to Storybook docs. Also Storybook is notoriusly slow, and does not handle basic things, like crashes, stack trases, error messages or adding new files and links very well. It is rather easy to lose half an hour in trying to make component work, just to find out that storybook swallowed the error message.

Another missing piece of a low-code way of doing things in behavior-driven design[7] way. Essentially creating human readable behavioral specification of components, and letting designers and business owners to write the spesifications.

  1. See Literate Programming in wikipedia. Literate programming was invented by Donald Knuth, professor emeritus at Stanford university. He considered it as the 'final form' of a program. ↩︎

  2. MDX is an authorable format that lets you seamlessly write JSX in your Markdown documents. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast 🚀. ↩︎

  3. Typescript is a superset of JavaScript by Microsoft, that seeks to bring static typing into dynamic JavaScript. It is essentially a computer-readable specification, that enables better developer tooling. ↩︎

  4. jsDoc is an API documentation generator for JavaScript. ↩︎

  5. Storybook Storybook is an open source tool for building UI components and pages in isolation. It streamlines UI development, testing, and documentation. ↩︎

  6. See Test-driven development in wikipedia. ↩︎

  7. See Human-friendly specifications are the key to better software in Eficode blog. ↩︎

Backlinks

No related notes